Logging／Observability 基礎

貝老闆（慌張衝進來）：小可小可！客戶說我們的「AI 智慧報表」按了沒反應，我打開 Console 看——欸？乾乾淨淨一片空耶！

小可（皺眉）：你是去裝潢公司請人刷油漆嗎？怎麼乾淨成這樣？

貝老闆：可是 AI 跟我說「Errors handled」，應該沒問題吧？

小可（翻白眼）：那叫「把錯誤吞掉，眼不見為淨」。我打給好威。

好威（電話那頭）：哈哈哈，你這叫「蒙著眼睛找針」。Console 空空通常三種可能：沒打 Log、try/catch 之後什麼都沒寫、或是只在本地印出來但雲端沒收到。先讓系統學會講話，才知道哪裡痛。

貝老闆：那我現在該怎麼辦？

好威：很簡單，跟 AI 說：幫我加結構化 Log；做健康檢查跟指標；開追蹤。先從壞掉的那顆按鈕開始。

概念拆解

1）Logging：系統的「流水帳日記」

把系統做的事寫下來，出事時才知道發生了什麼。基本分級：DEBUG/INFO/WARN/ERROR。

• 怎麼做：在重要的地方寫 Log，比如使用者點了按鈕、呼叫外部服務、查資料庫、出錯的地方。記時間、誰觸發的、做了什麼、結果如何。
• 找 AI 幫忙：問它「幫我做一個結構化 JSON log，包含 timestamp、user_id、request_id、狀態、耗時」。

2）Metrics：系統的「健康檢查表」

像量血壓、量脈搏。要量 API 速度、錯誤率、使用量、資源用多少。

• 怎麼做：在 API 回應前記錄一筆「執行一次」與耗時，設定錯誤率超過多少就通知。
• 找 AI 幫忙：問它「用 Prometheus 幫我記錄 /checkout API 的請求次數、延遲，並示範 Grafana 面板」。

3）Tracing：系統的「麵包屑路線圖」

讓每個請求都有一張地圖，知道它跑過哪裡卡在哪。

• 怎麼做：用 OpenTelemetry 產生 trace_id，從第一站傳到最後一站。
• 找 AI 幫忙：問它「幫我在 FastAPI 專案加 OpenTelemetry，並在所有 Log 加 trace_id」。

最小可行觀測（MVO）清單

1. 結構化 Log：統一 JSON 格式，至少要有時間、層級、服務、環境、request_id、user_id、動作、結果、錯誤、耗時。
2. 關鍵指標：每個主要 API 記請求數、錯誤數、耗時，設簡單告警。
3. 基本追蹤：在入口加 trace_id，跨服務帶著走。
4. 成本控制：Production 留 7 天，其他環境留 3 天，過期自動壓縮。

Takeaways

A. 先讓系統會講話： 沒 Log 就像黑暗中找東西，請 AI 幫你寫出要記什麼欄位的樣板。

B. 指標少而準： 先抓最關鍵的幾個健康指標，讓 AI 幫你做監控面板。

C. 追蹤先解最常壞的地方： 別一次全導，挑最重要的流程先做。

D. 控制雲端成本： 請 AI 幫你設定保留天數、取樣率，算清楚錢。

今日提問

你的系統哪條流程最容易出錯？用上面 MVO 清單先試做一條，留言分享你會先打哪支 Log。